---
title: Installation
description: How to install Pyrefly
---

Pyrefly is available on [PyPI](https://pypi.org/project/pyrefly/) with a new release every Monday. We often release more frequently when shipping new features and bug fixes.

## Install

You can use `uv`, `poetry`, `pip`, `pixi` or `conda` to install Pyrefly. The following commands show you how to install Pyrefly and run 2 basic commands: `init` and `check`.

* `pyrefly init` will update your `pyproject.toml` file (or create a `pyrefly.toml` file) in your project directory, including some basic configuration. It will also attempt to [migrate](../migrating-to-pyrefly) your existing type checker configuration.
* `pyrefly check --summarize-errors` will run the Pyrefly type checker on your project, providing a list of type errors and a summary of error types. The `--summarize-errors` flag is optional, remove it if you don't want summary stats.
* `pyrefly check --suppress-errors` will mark all existing errors as ignored, allowing you to start with a clean check.


Simply `cd` into your project directory and run:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="pip" label="Pip" default>
    ```
    pip install pyrefly
    pyrefly init
    pyrefly check --summarize-errors
    ```
  </TabItem>
  <TabItem value="conda" label="Conda">
    ```
    conda install -c conda-forge pyrefly
    pyrefly init
    pyrefly check --summarize-errors
    ```
  </TabItem>
  <TabItem value="uv" label="UV">
    ```
    uvx pyrefly init
    uvx pyrefly check --summarize-errors
    ```
  </TabItem>
  <TabItem value="poetry" label="Poetry">
    ```
    poetry add --group dev pyrefly
    poetry run pyrefly init
    poetry run pyrefly check --summarize-errors
    ```
  </TabItem>
  <TabItem value="pixi" label="Pixi">
    ```
    pixi add pyrefly
    pixi run pyrefly init
    pixi run pyrefly check --summarize-errors
    ```
  </TabItem>
</Tabs>

## Configure

You can set up a basic configuration file to type-check your project. You can add configuration options to a `pyproject.toml` file or create a `pyrefly.toml` file in your project directory. All [configuration options are documented here](../configuration).

```
[tool.pyrefly]
search_path = [
    "example_directory/..."
]
```

Then, run `pyrefly check` again, and the tool will use your configuration options.

The tool may return a list of type errors; this is perfectly normal. You have a few options at this point:

1. Use `# pyrefly: ignore` comments to silence the errors. This will get your project to a clean type-checking state, and you can reduce the number of errors as you go. We've included a script that can do this for you:

```
pyrefly check --suppress-errors
```

2. Use extra configuration options to silence specific categories of errors or exclude files with more errors than average.

----

## Upgrading Pyrefly

Upgrading the version of Pyrefly you're using or a third-party library you depend on can reveal new type errors in your code. Fixing them all at once is often unrealistic. We've written scripts to help you temporarily silence them.

```
# Step 1
pyrefly check --suppress-errors
```

```
# Step 2
<run your formatter of choice>
```

```
# Step 3
pyrefly check --remove-unused-ignores
```

Repeat these steps until you achieve a clean formatting run and a clean type check.

This will add `# pyrefly: ignore` comments to your code, enabling you to silence errors and return to fix them later. This can make the process of upgrading a large codebase much more manageable.

----

## Add Pyrefly to CI

After your project passes type checks without errors, you can prevent new bugs from being introduced. Enforce this through CI (Continuous Integration) to prevent other maintainers from merging code with errors. Here is an example for GitHub.

Save your workflow in the following path within your repository:

```
.github/workflows/typecheck.yml
```

GitHub automatically detects `.yml` files within `.github/workflows/` and sets up the defined workflows.

```
name: Pyrefly Type Check

on:
  pull_request:
    branches: [main]
  workflow_dispatch:  # Allows manual triggering from the GitHub UI

jobs:
  typecheck:
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5

      # Install Python dependencies and create environment
      - name: Install dependencies and run type checking
        run: |
          python -m venv .venv
          source .venv/bin/activate
          python -m pip install --upgrade pip
          # Install your dependencies; adjust the following lines as needed
          pip install -r requirements-dev.txt

      - name: Install Pyrefly
        run: pip install pyrefly

      - name: Run Pyrefly Type Checker
        run: pyrefly check
```

### A few notes about this setup:

- Building your environment and installing dependencies will enhance type safety by checking the types of imports. *This is not required, but encouraged!*
- Simply drop in `pyrefly check` to existing workflows that build and test your environment.

```
      - name: Run Pyrefly Type Checker
        run: pyrefly check
```

- Your `pyrefly.toml` or Pyrefly configs in your `pyproject.toml` will be automatically detected. Learn how to [configure Pyrefly here](../configuration).

----

## Pre-commit

Pyrefly provides a [pre-commit hook](https://pre-commit.com/) so you can automatically type check files before they are committed.

We maintain a dedicated repository for this integration here: [facebook/pyrefly-pre-commit](https://github.com/facebook/pyrefly-pre-commit)

That repository contains:

- Two pre-commit hooks depending on your setup
- Installation instructions
- Example configuration snippets for your project and CI

To get started, follow the setup steps in the repo’s [README](https://github.com/facebook/pyrefly-pre-commit#readme).

### Install pre-commit

You only need to do this once per clone. You can also include this in your as script or in your build/setup commands like `setup.py` or `setup.cfg` so it's installed for everyone.

```bash
# 1. Once per clone
pip install pre-commit          # or pipx install pre‑commit
pre-commit install              # writes .git/hooks/pre-commit

# 2. Upgrade hooks when you bump versions in YAML
pre-commit autoupdate

# 3. Manual full run (good before the first push or when you add the hook)
pre-commit run --all-files
```

### Testing the hook

**1. Introduce a cheap error**

Edit any `.py` file and deliberately return `None` where the function is annotated to return `int`.

```python
def foo() -> int:
    return None
```

**2. Stage & commit**

Output:

```bash
git add test.py
git commit -m "test: pre‑commit hook check"
pyrefly check............................................................Failed
- hook id: pyrefly-typecheck-system
- exit code: 1

 INFO Checking project configured at `/myproject/pyrefly.toml`
ERROR /myproject/test.py:2:12-16: Returned type `None` is not assignable to declared return type `int` [bad-return]
```

You should see Pyrefly fail as above, preventing the commit from being created.

**3. Fix & recommit**

Correct the code, `git add` it again, and re‑run `git commit`; this time the hook passes.

### How this helps your project

- **Earlier feedback**: Developers see type mistakes immediately, not minutes later in CI.
- **Consistent enforcement**: Every commit—local or on CI—runs the same pyrefly check command.
- **Clean history**: Because Pyrefly checks before the commit object is created, you avoid "fix type error" fix‑up commits.
- **Culture of quality**: Blocking problems at the doorstep raises the baseline for new contributors.
